home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1996 February: Tool Chest / Apple Developer CD Series Tool Chest February 1996 (Apple Computer)(1996).iso / Tool Chest / Testing & Debugging / Virtual User tools / VU Assist Modules for MacApp / Assist Module MA 3.0 / READ ME FIRST!
Encoding:
Text File  |  1993-09-17  |  9.1 KB  |  220 lines  |  [TEXT/MPS ]
  1. **************************************************************************
  2. What is VUAssist?
  3. **************************************************************************
  4. The code contained in this folder is the source code for a MacApp 3.0
  5. compatible version of VUAssist.  VUAssist is a Virtual User assistance module
  6. for MacApp applications.  By building VUAssist into your MacApp application, 
  7. you will be able to manipulate the user interface of your application very 
  8. easily with Virtual User.  
  9.  
  10.  
  11. Technical Background
  12. --------- ----------
  13. In order to find the location of items in windows for V.U., Agent VU peruses 
  14. the content list of windows and the item list of dialogs.  For applications 
  15. which are not built with MacApp, these data structures can be accessed via 
  16. global variables by Agent VU.  For MacApp applications, however, items in 
  17. windows are subclasses of the class TView, which are not available to the 
  18. Agent via global data structures.   As a result, Agent VU can’t provide any 
  19. information about these items to V.U. in the normal way.
  20.  
  21. To work around this problem, Agent VU provides a hook which allows an 
  22. application to assist Agent VU by providing information about itself.  
  23. In this folder, we’ve provided VUAssist, an assistance module for MacApp 
  24. applications which can be hooked onto Agent VU to provide information about 
  25. a MacApp application. A developer can build a MacApp application with VUAssist 
  26. and then test the application with V.U..  V.U. will "recognize" many of the
  27. application's views which translate into standard user interface items: buttons,
  28. scroll bars, checkboxes, static text, editable text fields, popup menus, etc.
  29.  
  30.  
  31. The module exists as a unit called UVUAssist.  The unit consists of four files:   
  32. VUAssist.p, VUAssist.inc1.p, VUAssist.inc2.p, and VUAssist.a.
  33.  
  34.  
  35. -----------------------------------------------------------------------------
  36. What's New in this Version - 1.0a1 
  37. -----------------------------------------------------------------------------
  38. ******** Changes relative to the 1.0d11 version ********  
  39.  
  40. 1) VUAssist has been made compatible with MacApp 3.0.
  41.  
  42. 2) IVUAssist no longer installs the VUAssist handler or sets its idle frequency.  
  43. This is now the responsibility of the client of VUAssist (see "How To Use VUAssist" 
  44. below).
  45.  
  46. !!!!! NOTICE !!!!!
  47. 3) The instructions for building VUAssist into your application have changed 
  48. slightly since the 1.0d11 version or earlier versions.  The instructions given in the 
  49. Virtual User General Reference are also not valid for this version. The new instructions 
  50. are given below in the section "How To Use VUAssist".
  51.  
  52.  
  53. ******** Changes relative to the 1.0d7 version ********  
  54.  
  55. 1) VUAssist has now been defined as a descendant of TEventHandler.  This allows VUAssist 
  56. to be installed as a cohandler.  The frequency with which VUAssist's DoIdle routine is 
  57. called can now be controlled. This gives the user of VUAssist a convenient way to control 
  58. the responsiveness of the application to Virtual User.
  59.  
  60. 2) VUAssist's handling of TGridView objects has changed somewhat.  The cells of TGridView 
  61. objects now appear as "contentItems" to V.U. as opposed to "userItems".  This is more
  62. consistent with V.U.'s interface item hierarchy.  Useritems are really intended to describe
  63. Dialog Manager userItems while contentItems are effectively the "base class" of all interface
  64. items in V.U..  Since there is no class of interface items in V.U. which is intended to describe
  65. the cells of gridviews, they should be considered to belong to the "base class", contentItem.
  66.  
  67. 3) The feature of VUAssist which maps the cells of gridviews to "contentitems" can be disabled 
  68. through the boolean gridItemSupport argument to the IVUAssist method.
  69.  
  70. 4) The implementation of some of the methods of VUAssist have been modified to improve 
  71. performance.
  72.  
  73.  
  74. -----------------------------------------------------------------------------
  75. How to Use VUAssist
  76. -----------------------------------------------------------------------------
  77.  
  78. To build VUAssist into your MacApp application, follow the instructions
  79. below.  
  80.  
  81. For applications written in Object Pascal:
  82.  
  83. 1)  Modify your MAMake file to include the following:
  84.  
  85.     •    add the following to the list of OtherInterfaces
  86.         
  87.         "{SrcApp}UVUAssist.p"
  88.         
  89.     •    add the following to the list of OtherLinkFiles
  90.         
  91.         "{ObjApp}UVUAssist.a.o" ∂
  92.         "{ObjApp}UVUAssist.p.o" 
  93.     
  94.     •    add the additional dependencies:
  95.  
  96.         "{ObjApp}UVUAssist.p.o"    ƒ ∂
  97.                     "{SrcApp}UVUAssist.p" ∂
  98.                     "{SrcApp}UVUAssist.inc1.p" ∂
  99.                     "{SrcApp}UVUAssist.inc2.p" ∂
  100.                     {MacAppIntf} ∂
  101.                     {BuildingBlocksIntf}
  102.                     
  103.         "{ObjApp}UVUAssist.a.o"    ƒ ∂
  104.                             "{SrcApp}UVUAssist.a" 
  105.                             
  106. 2)     Modify or subclass your descendant of TApplication to do the following:
  107.                             
  108.     •    In MyApplication.IApplication, you must execute this:
  109.             NEW(gVUAssist);
  110.             gVUAssist.IVUAssist(gridItemSupport); { gridItemSupport must be a boolean expression.
  111.                                                     see "Altering the behavior of VUAssist
  112.                                                     for an explanation of gridItemSupport }
  113.             gVUAssist.SetIdleFreq(kVUAssistIdleFreq);
  114.             SELF.InstallCohandler(gVUAssist,true);
  115.             
  116.     •    In MyApplication.AboutToLoseControl you must execute this:
  117.             gVUAssist.SuspendMole;
  118.  
  119.     •    In MyApplication.RegainControl you must execute this:
  120.             gVUAssist.ResumeMole;
  121.  
  122.     •    In MyApplication.Close you must execute this BEFORE calling INHERITED Close:
  123.             SELF.InstallCohandler(gVUAssist,false);
  124.  
  125. 3)    Include the unit UVUAssist in your USES clause where appropriate.  Other units may 
  126.     need to be included along with UVUAssist if they are not already.
  127.  
  128.  
  129. For applications written in C++:
  130.  
  131. 1)  Modify your MAMake file to include the following:
  132.  
  133.     •    add the following to the list of OtherInterfaces
  134.         
  135.         "{SrcApp}UVUAssist.h"
  136.         
  137.     •    add the following to the list of OtherLinkFiles
  138.         
  139.         "{ObjApp}UVUAssist.a.o" ∂
  140.         "{ObjApp}UVUAssist.p.o" 
  141.     
  142.     •    add the additional dependencies:
  143.  
  144.         "{ObjApp}UVUAssist.p.o"    ƒ ∂
  145.                     "{SrcApp}UVUAssist.p" ∂
  146.                     "{SrcApp}UVUAssist.inc1.p" ∂
  147.                     "{SrcApp}UVUAssist.inc2.p" ∂
  148.                     {MacAppIntf} ∂
  149.                     {BuildingBlocksIntf}
  150.                     
  151.         "{ObjApp}UVUAssist.a.o"    ƒ ∂
  152.                             "{SrcApp}UVUAssist.a" 
  153.                             
  154. 2)     Modify or subclass your descendant of TApplication to do the following:
  155.                             
  156.     •    In MyApplication.IApplication, you must execute this:
  157.             gVUAssist = new TVUAssist;
  158.             gVUAssist->IVUAssist(gridItemSupport); /* gridItemSupport must be a boolean expression.
  159.                                                       see "Altering the behavior of VUAssist
  160.                                                       for an explanation of gridItemSupport */
  161.             gVUAssist->SetIdleFreq(kVUAssistIdleFreq);
  162.             this->InstallCohandler(gVUAssist, TRUE);
  163.             
  164.     •    In MyApplication.AboutToLoseControl you must execute this:
  165.             gVUAssist->SuspendMole();
  166.  
  167.     •    In MyApplication.RegainControl you must execute this:
  168.             gVUAssist->ResumeMole();
  169.  
  170.     •    In MyApplication.Close you must execute this BEFORE calling INHERITED Close:
  171.             this->InstallCohandler(gVUAssist,false);
  172.  
  173. 3)    Include the header file UVUAssist.h where appropriate.
  174.  
  175.         #ifndef __UVUASSIST__
  176.         #include "UVUAssist.h"
  177.         #endif
  178.  
  179. 4)    If you are using C++, make sure to use the VUAssist.a file which is included in the 
  180.     folder "C++ Interface to VUAssist" in place of the file with the same name which is 
  181.     found in the folder "VUAssist Source Code".
  182.  
  183.  
  184. -----------------------------------------------------------------------------
  185. Modifying the Behavior of VUAssist
  186. -----------------------------------------------------------------------------
  187.  
  188. 1) VUAssist Idle Frequency
  189.  
  190. VUAssist has now been defined to be a descendant TEventHandler.  An application's 
  191. responsiveness to V.U. queries can be controlled by setting the idle frequency of 
  192. VUAssist. Although nothing is done with this idle time, it forces the application to 
  193. awaken and call SystemTask with the application's context switched in.  This is necessary 
  194. for Agent VU, a driver, to get processing time.  Agent VU, in turn, calls VUAssist.  
  195. So, in a roundabout way, the application's responsiveness to V.U. can be controlled by 
  196. setting the idle frequency of VUAssist.
  197.  
  198. The default idle frequency is kVUAssistIdleFreq, which is set to 1.  You may want to alter 
  199. this by executing the following statement:
  200.  
  201.     gVUAssist.SetIdleFreq(newIdleFreq);
  202.  
  203. Note, however, that larger values of VUAssist's idle frequency will slow down the application's
  204. response to V.U. unless there is another cohandler with a very high idle frequency.
  205.  
  206.  
  207. 2) The gridItemSupport Argument
  208.  
  209. Note that the TVUAssist method IVUAssist now takes an argument, gridItemSupport.  This
  210. argument, if true, enables an optional feature of VUAssist where the cells of gridviews are
  211. recognized as individual user interface items by V.U..  Virtual User does not yet have a 
  212. gridview or list descriptor.  So, for the short term, the "gridItemSupport" feature treats
  213. each cell of a gridview as a "contentitem" in the V.U. scripting language.
  214.  
  215. In applications with very large gridviews, it may not be desirable to treat each cell in a
  216. gridview as a separate item in V.U..  This may severely hamper performance.  By setting the 
  217. value of the gridItemSupport argument to false, you will disable V.U.'s griditem support 
  218. feature and the cells of gridviews will not be seen as "contentItems" by V.U..  The cells will 
  219. be "invisible" to Virtual User.
  220.